问题

在每个类、接口、构造器、方法和域生命处都应该有详细的文档注释，那么好的文档注释有哪些元素？

解决

1. 如果要想使一个API真正可用，就必须为其编写文档。传统意义上的API文档是手动生成的，所以保持文档与代码同步是一件很繁琐的事情。Java环境提供了一种被称为Javadoc的实用工具来完成文档注释的编写；
2. 文档注释的三个部分：
   1. 第一部分是简述。文档中，对于属性和方法都是先有一个列表，然后才在后面一个一个的详细的说明；
   2. 第二部分是详细说明部分。该部分对属性或者方法进行详细的说明，在格式上没有什么特殊的要求，可以包含若干个点号；
   3. 第三部分是特殊说明部分。这部分包括版本说明、参数说明、返回值说明等。
      • @param b true 表示显示，false 表示隐藏
      • @return 没有返回值
3. 添加文档注释规范：
   1. 为了正确地编写API文档，必须在每个被导出的类、接口、构造器、方法和域声明之前增加一个文档注释；
   2. 方法的文档注释应该简洁的描述出它和客户端之间的约定。这个约定应该说明这个方法做了什么，而不是说明它是如何完成这项工作的。文档注释应该列举如下内容：
      • 前提条件（precondition） 前提条件是指为了使客户能够调用这个方法，而必须满足的条件；
      • 后置条件（postcondition） 所谓后置条件是指在调用成功完成之后，哪些条件必须要满足；
      • 副作用（side effect） 副作用是指系统状态中可以观察到的变化，它不是为了获得后置条件而明确要求的变化；
      • 类或者方法的线程安全性（thread safety）（详见70条） 当一个类的实例或者静态方法被并发使用时，这个类行为的并发情况。

结论

要为API编写文档，文档注释是最好、最有效的途径。对于所有可导出的API元素来说，使用文档注释应该被看作是强制性的。要采用一致的风格来遵循标准的约定。在文档注释内部出现任何HTML标签都是允许的，但是HTML字符必须要经过转义。